1   /*
2    * Copyright (C) 2007 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package com.google.common.collect;
18  
19  import com.google.common.annotations.GwtCompatible;
20  
21  import java.util.NoSuchElementException;
22  import java.util.Queue;
23  
24  /**
25   * A queue which forwards all its method calls to another queue. Subclasses
26   * should override one or more methods to modify the behavior of the backing
27   * queue as desired per the <a
28   * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
29   *
30   * <p><b>Warning:</b> The methods of {@code ForwardingQueue} forward
31   * <b>indiscriminately</b> to the methods of the delegate. For example,
32   * overriding {@link #add} alone <b>will not</b> change the behavior of {@link
33   * #offer} which can lead to unexpected behavior. In this case, you should
34   * override {@code offer} as well, either providing your own implementation, or
35   * delegating to the provided {@code standardOffer} method.
36   *
37   * <p>The {@code standard} methods are not guaranteed to be thread-safe, even
38   * when all of the methods that they depend on are thread-safe.
39   *
40   * @author Mike Bostock
41   * @author Louis Wasserman
42   * @since 2.0 (imported from Google Collections Library)
43   */
44  @GwtCompatible
45  public abstract class ForwardingQueue<E> extends ForwardingCollection<E>
46      implements Queue<E> {
47  
48    /** Constructor for use by subclasses. */
49    protected ForwardingQueue() {}
50  
51    @Override protected abstract Queue<E> delegate();
52  
53    @Override
54    public boolean offer(E o) {
55      return delegate().offer(o);
56    }
57  
58    @Override
59    public E poll() {
60      return delegate().poll();
61    }
62  
63    @Override
64    public E remove() {
65      return delegate().remove();
66    }
67  
68    @Override
69    public E peek() {
70      return delegate().peek();
71    }
72  
73    @Override
74    public E element() {
75      return delegate().element();
76    }
77  
78    /**
79     * A sensible definition of {@link #offer} in terms of {@link #add}. If you
80     * override {@link #add}, you may wish to override {@link #offer} to forward
81     * to this implementation.
82     * 
83     * @since 7.0
84     */
85    protected boolean standardOffer(E e) {
86      try {
87        return add(e);
88      } catch (IllegalStateException caught) {
89        return false;
90      }
91    }
92  
93    /**
94     * A sensible definition of {@link #peek} in terms of {@link #element}. If you
95     * override {@link #element}, you may wish to override {@link #peek} to
96     * forward to this implementation.
97     * 
98     * @since 7.0
99     */
100   protected E standardPeek() {
101     try {
102       return element();
103     } catch (NoSuchElementException caught) {
104       return null;
105     }
106   }
107 
108   /**
109    * A sensible definition of {@link #poll} in terms of {@link #remove}. If you
110    * override {@link #remove}, you may wish to override {@link #poll} to forward
111    * to this implementation.
112    * 
113    * @since 7.0
114    */
115   protected E standardPoll() {
116     try {
117       return remove();
118     } catch (NoSuchElementException caught) {
119       return null;
120     }
121   }
122 }